Restful风格的Retrofit2网络请求器

简介

Retrofit2 以其简易的接口配置、强大的扩展支持、优雅的代码结构受到大家的追捧。Retrofit2 的 API 接口定义极具 Restful 风格，且很好的与okhttp3相互结合形成一个高效简洁的网络请求库。

//通过接口定义你的api
public interface GitHubService {
  @GET("users/{user}/repos")
  Call<List<Repo>> listRepos(@Path("user") String user);
}

//再由Retrofit生成 `GitHubService`接口相对应的方法
Retrofit retrofit = new Retrofit.Builder()
    .baseUrl("https://api.github.com/")
    .build();

GitHubService service = retrofit.create(GitHubService.class);

1 2	//通过GitHubService生成的方法进行网络请求 Call<List<Repo>> repos = service.listRepos("octocat");

详情请见Retrofit2官方教程

原理

Retrofit2库源码中最让人眼前一亮的设计是通过java的动态代理将接口中的每个方法和注解转化成一个单独的ServiceMethod，之后在ServiceMethod中查找合适的CallAdapterFactory和ConverterFactory对数据进行处理。

Java的注解和动态代理原理
CallAdapter及其Factory设计思路
Converter及其Factory设计思路

以上亦是整个库的核心原理。

解析

预先准备

Retrofit retrofit = new Retrofit.Builder()
    .baseUrl("https://api.github.com/")
    .addConverterFactory(GsonConverterFactory.create())
    .addCallAdapterFactory(RxJavaCallAdapterFactory.create())
    .build();

GitHubService service = retrofit.create(GitHubService.class);

整个流程由Retrofit的build开始，将一些必须的参数如baseUrl,CallAdapterFactory,ConverterFactory传入到Retrofit中，之后通过create方法对接口文件中的方法建立动态代理，使得每当方法被调用时都能走到代理的方法中。

public <T> T create(final Class<T> service) {
    Utils.validateServiceInterface(service);
    if (validateEagerly) {
      eagerlyValidateMethods(service);
    }
    return (T) Proxy.newProxyInstance(service.getClassLoader(), new Class<?>[] { service },
        new InvocationHandler() {
          private final Platform platform = Platform.get();

          @Override public Object invoke(Object proxy, Method method, @Nullable Object[] args)
              throws Throwable {
            // If the method is a method from Object then defer to normal invocation.
            if (method.getDeclaringClass() == Object.class) {
              return method.invoke(this, args);
            }
            if (platform.isDefaultMethod(method)) {
              return platform.invokeDefaultMethod(method, service, proxy, args);
            }
            ServiceMethod<Object, Object> serviceMethod =
                (ServiceMethod<Object, Object>) loadServiceMethod(method);
            OkHttpCall<Object> okHttpCall = new OkHttpCall<>(serviceMethod, args);
            return serviceMethod.callAdapter.adapt(okHttpCall);
          }
        });
}

调用

上面已经说过，当service中的方法被调用时会走入之前的动态代理方法中，那看看该代理方法中做了哪些事情。
首先通过 ServiceMethodCache 查看是否有该方法的缓存，如果没有则通过ServiceMethod的Builder传入retrofit构建出来。

在 ServiceMethod 的builder构建方法中

public ServiceMethod build() {
	// 查找 合适的 calladapter
	callAdapter = createCallAdapter();

	// 查找合适的结果转化器
	responseType = callAdapter.responseType();
	responseConverter = createResponseConverter();

	// 编译api方法上的注解，并转化为相应http请求信息，如get,post,header
	for (Annotation annotation : methodAnnotations) {
		parseMethodAnnotation(annotation);
	}

	if (httpMethod == null) {
		throw methodError("HTTP method annotation is required (e.g., @GET, @POST, etc.).");
	}

	if (!hasBody) {
		if (isMultipart) {
		  throw methodError(
		      "Multipart can only be specified on HTTP methods with request body (e.g., @POST).");
		}
		if (isFormEncoded) {
		  throw methodError("FormUrlEncoded can only be specified on HTTP methods with "
		      + "request body (e.g., @POST).");
		}
	}

	// 获取方法中的参数数据
	int parameterCount = parameterAnnotationsArray.length;
	parameterHandlers = new ParameterHandler<?>[parameterCount];
	for (int p = 0; p < parameterCount; p++) {
		Type parameterType = parameterTypes[p];
		if (Utils.hasUnresolvableType(parameterType)) {
		  throw parameterError(p, "Parameter type must not include a type variable or wildcard: %s",
		      parameterType);
		}

		Annotation[] parameterAnnotations = parameterAnnotationsArray[p];
		if (parameterAnnotations == null) {
		  throw parameterError(p, "No Retrofit annotation found.");
		}

		parameterHandlers[p] = parseParameter(p, parameterType, parameterAnnotations);
	}

	if (relativeUrl == null && !gotUrl) {
		throw methodError("Missing either @%s URL or @Url parameter.", httpMethod);
	}
	if (!isFormEncoded && !isMultipart && !hasBody && gotBody) {
		throw methodError("Non-body HTTP method cannot contain @Body.");
	}
	if (isFormEncoded && !gotField) {
		throw methodError("Form-encoded method must contain at least one @Field.");
	}
	if (isMultipart && !gotPart) {
		throw methodError("Multipart method must contain at least one @Part.");
	}

	return new ServiceMethod<>(this);
}

CallAdapterFactory和CallAdapter

再说CallAddapterFactory前，先说说这个是干什么用的。简而言之就是将Retrofit原生默认的call这个请求对象转换成开发者想要的对象，比如说RxJava中Observable之类。

在动态代理方法中，可以看到有这么一行代码，这里的OkHttpCall是对于OkHttp的一个封装，也就是说我们通过Retrofit进行网络请求实质就是通过OkHttp来进行请求。

1	OkHttpCall<Object> okHttpCall = new OkHttpCall<>(serviceMethod, args);

随之其后的是 callAdapter的adapt方法

1	return serviceMethod.callAdapter.adapt(okHttpCall);

serviceMethod 中的 callAdapter 则是在 Retrofit 的 adapterFactories 中查找而得（之前在Retrofit的构建过程中添加addCallAdapterFactory()）

int start = adapterFactories.indexOf(skipPast) + 1;
   for (int i = start, count = adapterFactories.size(); i < count; i++) {
     CallAdapter<?, ?> adapter = adapterFactories.get(i).get(returnType, annotations, this);
     if (adapter != null) {
       return adapter;
     }
   }

查找规则则是通过在 CallAdapterFactory 的get方法中判断returnType来进行，一旦查找成功后就会返回相应的CallAdapter。

比如说在 Retrofit2 自带的 DefaultCallAdapterFactory 则是判断 getRawType(returnType) == Call.class，若是则返回原生的Call

在 Rxjava2CallAdapterFactory 中是判断 returnType 是否等于 Completable、Flowable、Single、Maybe或者Observable，是则返回Rxjava2CallAdapter.

最后在 CallAdapter 的 adapter方法中可以将传入的call对象转换成自己想要的对象。

ConverterFactory和Converter

Converter 是负责对请求数据和返回数据进行转换的功能，设计思路与 CallAdapterFactory 相似。在 ConverterFactory中有两个比较重要的方法，一个是 requestBodyConverter,这个方法也是通过判断传入的 Type 类型来决定对请求数据的 RequestBodyConverter器，要求返回Converter<?, RequestBody>类型。
另一个是responseBodyConverter,要求返回Converter<ResponseBody, ?>类型。

RequestBodyConverter一般会在 @Body,@Part以及@PartMap的参数解析中使用，用来将请求的数据转换到标准的RequestBody格式。

比如说在 @Part 注解下的参数解析中，由于参数的类型为RequestBody，则ConverterFactory 会优先返回Retrofit自带的 BuiltInConverters 中的 RequestBodyConverter，负责转换RequestBody。

而在 @Body 注解下的参数解析中，则有可能会进入 GsonConverterFactory的 GsonRequestBodyConverter中，负责将 @Body声明的实体转换成json字符创。

// BuiltInConverters下的requestBodyConverter方法
@Override
public Converter<?, RequestBody> requestBodyConverter(Type type,
  	Annotation[] parameterAnnotations, Annotation[] methodAnnotations, Retrofit retrofit) {
	if (RequestBody.class.isAssignableFrom(Utils.getRawType(type))) {
	  return RequestBodyConverter.INSTANCE;
	}
	return null;
}

// GsonConverterFactory 下的 requestBodyConverter 方法
// 来者不拒。。
@Override
public Converter<?, RequestBody> requestBodyConverter(Type type,
  	Annotation[] parameterAnnotations, Annotation[] methodAnnotations, Retrofit retrofit) {
	TypeAdapter<?> adapter = gson.getAdapter(TypeToken.get(type));
	return new GsonRequestBodyConverter<>(gson, adapter);
}

ResponseBodyConverter则是在 okHttpCall 访问网络结束后调用

 // OkHttpCall类中的方法
Response<T> parseResponse(okhttp3.Response rawResponse) throws IOException {
	//...省略部分代码
	try {
     T body = serviceMethod.toResponse(catchingBody);
     return Response.success(body, rawResponse);
   } catch (RuntimeException e) {
     // If the underlying source threw an exception, propagate that rather than indicating it was
     // a runtime exception.
     catchingBody.throwIfCaught();
     throw e;
   }
}

// ServiceMethod类中的方法
/** Builds a method return value from an HTTP response body. */
R toResponse(ResponseBody body) throws IOException {
   return responseConverter.convert(body);
}

其中 serviceMethod.toResponse()即会调用之前通过ConverterFactory得到的responseConverter.convert方法，将ResponseBody转化为自己想要的数据类型。
这里要注意一点，在之前说过的CallAdapter中有一个responseType()方法，此方法返回的数据类型要与responseConverter.convert(body)的返回类型保持一致。

结语

Retrofit 本身是通过 OkHttp3 实现的网络请求，首先通过动态代理的方式为api service 中的每一个方法一一对应的生成了ServiceMethod；同时通过提供自定义CallAdapterFactory的方式能够将默认的Call请求方法转换成开发者自己想要的数据对象；不知如此，还通过自定义ConverterFactory的方式能够自由的进行请求数据与RequestBody,ResponseBody与返回数据的数据转换。

通过以上所介绍，Retrofit2比较重要的几个原理部分都进行了简单说明。
Retrofit2实现了自身强大的功能与扩展性，能够方便的实现开发者自己想要的功能，同时其美丽而又简洁的代码也是我们借鉴的一个目标。

参考资料：